home *** CD-ROM | disk | FTP | other *** search
/ This Disc Bytes! / Power Computing - The Disc 2 - This Disc Bytes.ISO / mac / CodeWarrior 7 Lite for 68K / MacOS Support / Headers / Universal Headers / Translation.h < prev    next >
Text File  |  1995-07-06  |  12KB  |  310 lines
  1. /*
  2.      File:        Translation.h
  3.  
  4.      Contains:    Translation Manager (Macintosh Easy Open) Interfaces.
  5.  
  6.      Version:    Technology:    Macintosh Easy Open 1.1
  7.                  Package:    Universal Interfaces 2.1 in “MPW Latest” on ETO #18
  8.  
  9.      Copyright:    © 1984-1995 by Apple Computer, Inc.
  10.                  All rights reserved.
  11.  
  12.      Bugs?:        If you find a problem with this file, use the Apple Bug Reporter
  13.                  stack.  Include the file and version information (from above)
  14.                  in the problem description and send to:
  15.                      Internet:    apple.bugs@applelink.apple.com
  16.                      AppleLink:    APPLE.BUGS
  17.  
  18. */
  19.  
  20. #ifndef __TRANSLATION__
  21. #define __TRANSLATION__
  22.  
  23.  
  24. #ifndef __TYPES__
  25. #include <Types.h>
  26. #endif
  27. /*    #include <ConditionalMacros.h>                                */
  28.  
  29. #ifndef __FILES__
  30. #include <Files.h>
  31. #endif
  32. /*    #include <MixedMode.h>                                        */
  33. /*    #include <OSUtils.h>                                        */
  34. /*        #include <Memory.h>                                        */
  35. /*    #include <Finder.h>                                            */
  36.  
  37. #ifndef __COMPONENTS__
  38. #include <Components.h>
  39. #endif
  40.  
  41. #ifndef __TRANSLATIONEXTENSIONS__
  42. #include <TranslationExtensions.h>
  43. #endif
  44. /*    #include <Quickdraw.h>                                        */
  45. /*        #include <QuickdrawText.h>                                */
  46.  
  47. #ifdef __cplusplus
  48. extern "C" {
  49. #endif
  50.  
  51. #if PRAGMA_ALIGN_SUPPORTED
  52. #pragma options align=mac68k
  53. #endif
  54.  
  55. #if PRAGMA_IMPORT_SUPPORTED
  56. #pragma import on
  57. #endif
  58.  
  59. typedef short DocOpenMethod;
  60.  
  61.  
  62. enum {
  63.     domCannot,
  64.     domNative,
  65.     domTranslateFirst,
  66.     domWildcard
  67. };
  68.  
  69. /* 0L terminated array of OSTypes, or FileTypes*/
  70. typedef OSType TypesBlock[64];
  71.  
  72. typedef OSType *TypesBlockPtr;
  73.  
  74. /* Progress dialog resource ID*/
  75.  
  76. enum {
  77.     kTranslationScrapProgressDialogID = -16555
  78. };
  79.  
  80. /* block of data that describes how to translate*/
  81. struct FileTranslationSpec {
  82.     OSType                            componentSignature;
  83.     const void                        *translationSystemInfo;
  84.     FileTypeSpec                    src;
  85.     FileTypeSpec                    dst;
  86. };
  87. typedef struct FileTranslationSpec FileTranslationSpec;
  88.  
  89. typedef FileTranslationSpec *FileTranslationSpecArrayPtr;
  90.  
  91. /*****************************************************************************************
  92. * 
  93. *   GetFileTypesThatAppCanNativelyOpen
  94. * 
  95. *  This routine returns a list of all FileTypes that an application can open by itself
  96. * 
  97. *  Enter:    appVRefNumHint        volume where application resides (can be wrong, and if is, will be used as a starting point)
  98. *             appSignature        signature (creator) of application
  99. *             nativeTypes            pointer to a buffer to be filled with up to 64 FileTypes
  100. * 
  101. *  Exit:    nativeTypes            zero terminated array of FileTypes that can be opened by app
  102. */
  103. extern pascal OSErr GetFileTypesThatAppCanNativelyOpen(short appVRefNumHint, OSType appSignature, FileType *nativeTypes)
  104.  TWOWORDINLINE(0x701C, 0xABFC);
  105. /*****************************************************************************************
  106. * 
  107. *  ExtendFileTypeList
  108. * 
  109. *  This routine makes a new list of file types that can be translated into a type in the given list
  110. *  Used by StandardFile
  111. * 
  112. *  Enter:    originalTypeList        pointer to list of file types that can be opened
  113. *             numberOriginalTypes        number of file types in orgTypeList
  114. *              extendedTypeList        pointer to a buffer to be filled with file types
  115. *             numberExtendedTypes        max number of file types that can be put in extendedTypeList
  116. * 
  117. *  Exit:    extendedTypeList        buffer filled in with file types that can be translated
  118. *             numberExtendedTypes        number of file types put in extendedTypeList
  119. */
  120. extern pascal OSErr ExtendFileTypeList(const FileType *originalTypeList, short numberOriginalTypes, FileType *extendedTypeList, short *numberExtendedTypes)
  121.  TWOWORDINLINE(0x7009, 0xABFC);
  122. /*****************************************************************************************
  123. * 
  124. * 
  125. *  This routine checks if a file can be opened by a particular application.
  126. *  If so, it returns if it needs to be translated first, and if so then how.
  127. *  The FileTypes that the app can open are specified by nativelyOpenableTypes,
  128. *  or if it is NULL, GetFileTypesThatAppCanNativelyOpen is called.
  129. * 
  130. *  Enter:    targetDocument        document to check if it can be opened
  131. *             appVRefNumHint        vRefNum of application to open doc ( can be wrong, and if is, will be used as a starting point)
  132. *             appSignature        signature (creator) of application to open doc
  133. *             nativeTypes            zero terminated list of FileTypes app can open natively, or NULL to use default list
  134. *             onlyNative            whether to consider if document can be translated before opening
  135. *             howToOpen            pointer to buffer in which to put how the document can be opened
  136. *             howToTranslate        pointer to buffer in which to put a FileTranslationSpec record
  137. * 
  138. *  Exit:    howToOpen            whether file needs to be translated to be read
  139. *             howToTranslate        if file can be translated, buffer filled in with how to translate
  140. *             returns                noErr, noPrefAppErr
  141. */
  142. extern pascal OSErr CanDocBeOpened(const FSSpec *targetDocument, short appVRefNumHint, OSType appSignature, const FileType *nativeTypes, Boolean onlyNative, DocOpenMethod *howToOpen, FileTranslationSpec *howToTranslate)
  143.  TWOWORDINLINE(0x701E, 0xABFC);
  144. /*****************************************************************************************
  145. * 
  146. *  GetFileTranslationPaths
  147. * 
  148. *  This routine returns a list of all ways a translation can occure to or from a FileType.
  149. *  The app is checked to exist.  The hint for each app is the VRefNum and DTRefNum
  150. * 
  151. *  Enter:    srcDoc            source file or NULL for all matches
  152. *             dstDoc            destination FileType or NULL for all matches
  153. *             maxResultCount
  154. *             resultBuffer
  155. *  Exit:    number of paths
  156. */
  157. extern pascal short GetFileTranslationPaths(FSSpec *srcDocument, FileType dstDocType, unsigned short maxResultCount, FileTranslationSpecArrayPtr resultBuffer)
  158.  TWOWORDINLINE(0x7038, 0xABFC);
  159. /*****************************************************************************************
  160. * 
  161. *  GetPathFromTranslationDialog
  162. * 
  163. *  This routine, with a given document, application, and a passed typelist will display the
  164. *  Macintosh Easy Open translation dialog allowing the user to make a choice.  The choice
  165. *  made will be written as a preference (so the next call to CanDocBeOpened() will work).
  166. *  The routine returns the translation path information.
  167. * 
  168. *  Enter:    theDocument            FSSpec to document to open
  169. *             theApplication        FSSpec to application to open document
  170. *             typeList            Nil terminated list of FileType's (e.g. SFTypeList-like) of types
  171. *                                 you would like the documented translated to.  Order most perferred
  172. *                                 to least.
  173. * 
  174. *  Exit:    howToOpen            Translation method needed to open document
  175. *             howToTranslate        Translation specification
  176. *             returns                Any errors that might occur.
  177. */
  178. extern pascal OSErr GetPathFromTranslationDialog(const FSSpec *theDocument, const FSSpec *theApplication, TypesBlockPtr typeList, DocOpenMethod *howToOpen, FileTranslationSpec *howToTranslate)
  179.  TWOWORDINLINE(0x7037, 0xABFC);
  180. /*****************************************************************************************
  181. * 
  182. *   TranslateFile
  183. * 
  184. *  This routine reads a file of one format and writes it to another file in another format. 
  185. *  The information on how to translated is generated by the routine CanDocBeOpened.
  186. *  TranslateFile calls through to the TranslateFile Extension's DoTranslateFile routine.  
  187. *  The destination file must not exist.  It is created by this routine.  
  188. * 
  189. *  Enter:    sourceDocument            input file to translate
  190. *             destinationDocument        output file of translation
  191. *             howToTranslate            pointer to info on how to translate
  192. *  Exit:    returns                    noErr, badTranslationSpecErr 
  193. */
  194. extern pascal OSErr TranslateFile(const FSSpec *sourceDocument, const FSSpec *destinationDocument, const FileTranslationSpec *howToTranslate)
  195.  TWOWORDINLINE(0x700C, 0xABFC);
  196. /*****************************************************************************************
  197. * 
  198. *   GetDocumentKindString
  199. * 
  200. *  This routine returns the string the Finder should show for the "kind" of a document
  201. *  in the GetInfo window and in the kind column of a list view.  
  202. * 
  203. *  Enter:    docVRefNum        The volume containing the document
  204. *             docType            The catInfo.fdType of the document
  205. *             docCreator        The catInfo.fdCreator of the document
  206. *             kindString        pointer to where to return the string
  207. * 
  208. *  Exit:    kindString        pascal string.  Ex: "\pSurfCalc spreadsheet"
  209. *             returns            noErr, or afpItemNoFound if kind could not be determined
  210. */
  211. extern pascal OSErr GetDocumentKindString(short docVRefNum, OSType docType, OSType docCreator, Str63 kindString)
  212.  TWOWORDINLINE(0x7016, 0xABFC);
  213. /*****************************************************************************************
  214. * 
  215. *  GetTranslationExtensionName
  216. * 
  217. *  This routine returns the translation system name from a specified TranslationSpec
  218. * 
  219. *  Enter:    translationMethod    The translation path to get the translation name from
  220. * 
  221. *  Exit:    extensionName        The name of the translation system
  222. *             returns                Any errors that might occur
  223. */
  224. extern pascal OSErr GetTranslationExtensionName(const FileTranslationSpec *translationMethod, Str31 extensionName)
  225.  TWOWORDINLINE(0x7036, 0xABFC);
  226. /*****************************************************************************************
  227. * 
  228. *  GetScrapDataProcPtr
  229. * 
  230. *  This is a prototype for the function you must supply to TranslateScrap. It is called to 
  231. *  get the data to be translated.  The first call TranslateScrap will make to this is to
  232. *  ask for the 'fmts' data.  That is a special.   You should resize and fill in the handle
  233. *  with a list all the formats that you have available to be translated, and the length of each.
  234. *  (See I.M. VI 4-23 for details of 'fmts').  It will then be called again asking for one of  
  235. *  the formats that 'fmts' list said was available.
  236. * 
  237. *  Enter:    requestedFormat            Format of data that TranslateScrap needs.
  238. *             dataH                    Handle in which to put the requested data
  239. *             srcDataGetterRefCon        Extra parameter for you passed to TranslateScrap
  240. *             
  241. *  Exit:    dataH                    Handle is resized and filled with data in requested format
  242. */
  243. typedef pascal OSErr (*GetScrapDataProcPtr)(ScrapType requestedFormat, Handle dataH, void *srcDataGetterRefCon);
  244.  
  245. #if GENERATINGCFM
  246. typedef UniversalProcPtr GetScrapDataUPP;
  247. #else
  248. typedef GetScrapDataProcPtr GetScrapDataUPP;
  249. #endif
  250.  
  251. enum {
  252.     uppGetScrapDataProcInfo = kPascalStackBased
  253.          | RESULT_SIZE(SIZE_CODE(sizeof(OSErr)))
  254.          | STACK_ROUTINE_PARAMETER(1, SIZE_CODE(sizeof(ScrapType)))
  255.          | STACK_ROUTINE_PARAMETER(2, SIZE_CODE(sizeof(Handle)))
  256.          | STACK_ROUTINE_PARAMETER(3, SIZE_CODE(sizeof(void*)))
  257. };
  258.  
  259. #if GENERATINGCFM
  260. #define NewGetScrapDataProc(userRoutine)        \
  261.         (GetScrapDataUPP) NewRoutineDescriptor((ProcPtr)(userRoutine), uppGetScrapDataProcInfo, GetCurrentArchitecture())
  262. #else
  263. #define NewGetScrapDataProc(userRoutine)        \
  264.         ((GetScrapDataUPP) (userRoutine))
  265. #endif
  266.  
  267. #if GENERATINGCFM
  268. #define CallGetScrapDataProc(userRoutine, requestedFormat, dataH, srcDataGetterRefCon)        \
  269.         CallUniversalProc((UniversalProcPtr)(userRoutine), uppGetScrapDataProcInfo, (requestedFormat), (dataH), (srcDataGetterRefCon))
  270. #else
  271. #define CallGetScrapDataProc(userRoutine, requestedFormat, dataH, srcDataGetterRefCon)        \
  272.         (*(userRoutine))((requestedFormat), (dataH), (srcDataGetterRefCon))
  273. #endif
  274.  
  275. typedef GetScrapDataUPP GetScrapData;
  276.  
  277. /*****************************************************************************************
  278. * 
  279. *  TranslateScrap
  280. * 
  281. *  This routine resizes the destination handle and fills it with data of the requested format.
  282. *  The data is generated by translated one or more source formats of data supplied by
  283. *  the procedure srcDataGetter.  
  284. *  This routine is automatically called by GetScrap and ReadEdition.  You only need to call
  285. *  this if you need to translated scrap style data, but are not using the ScrapMgr or EditionMgr.
  286. * 
  287. *  Enter:    sourceDataGetter            Pointer to routine that can get src data
  288. *             sourceDataGetterRefCon        Extra parameter for dataGetter
  289. *             destinationFormat            Format of data desired
  290. *             destinationData                Handle in which to store translated data
  291. *             
  292. *  Exit:    dstData                        Handle is resized and filled with data in requested format
  293. */
  294. extern pascal OSErr TranslateScrap(GetScrapData sourceDataGetter, void *sourceDataGetterRefCon, ScrapType destinationFormat, Handle destinationData, short progressDialogID)
  295.  TWOWORDINLINE(0x700E, 0xABFC);
  296.  
  297. #if PRAGMA_IMPORT_SUPPORTED
  298. #pragma import off
  299. #endif
  300.  
  301. #if PRAGMA_ALIGN_SUPPORTED
  302. #pragma options align=reset
  303. #endif
  304.  
  305. #ifdef __cplusplus
  306. }
  307. #endif
  308.  
  309. #endif /* __TRANSLATION__ */
  310.